BBS Toolkit/BBS Toolkit.iso/qbbs/raff_106.zip/RAFF.DOC

Text File | 1992-06-15 | 25KB | 564 lines

               RAFF - Remote Access File Find
                Version 1.00

          The Combined Files/Newfiles/Search Lister
            for RemoteAccess and SuperBBS

               (c) 1992 M.Schnitkemper
                Postbox 7462
                   W-4400 Münster



┌────────────────────────────────────────────────────────────────────────────┐
│                              Introduction                                  │
└────────────────────────────────────────────────────────────────────────────┘

Hi folks,
First of all I should say that  I hate to write documentations. On the  result
you got only a  short description of RAFF  along with the program  as I assume
that  you  are  an  experienced  system  operator  and know how to install any
external door at your BBS.

This  application  is  designed  to  run  under  RemoteAccess or SuperBBS as a
replacement for menu types  31, 35, 36 and  37. It maybe useful  for those who
have  serious  problems  to  run   "the  other"  utility  under  a   multinode
environment.

RAFF provides you with the following features:

■ Easy installation

■ Local/global filearea access mode

■ Change filearea without leaving RAFF

■ Searching options for filenames, keywords, newfiles or date

■ Full support for read/only media such as CDROM disk

■ Includes processing of the  special FILES.BBS format, introduced by  the EFT
  filetransfer manager

■ Respecting all settings of the environment such as security level and flags

■ SysOp defined supportfiles

■ Multiline/Multitask and network aware

■ All informations are retrieved from existing files, no files are created  or
  modified in any way

■ Own ANSI emulation driver included. Supports all colour and positioning
  commands

■ The usage of RAFF is (still) free of charge!



┌────────────────────────────────────────────────────────────────────────────┐
│                             The Installation                               │
└────────────────────────────────────────────────────────────────────────────┘

The installation is quite easy,  no special procedures or configuration  files
are needed. First you have to  create a type7 menu entry and  place "RAFF.EXE"
into your system  directory. Note that  your environment variable  "RA" (SBBS:
"SBBS") must point to this path. At least, you have to set the "/A"-switch  to
tell RAFF  the path  of the  current filearea.  Depending on  the BBS  you are
operating,  there  are  to  different  kind  of  settings:  Use  "/A*0"  for a
RemoteAccess- or "/A*U" for a SuperBBS installation.

You can use one or more of the following switches on the commandline:

    /A      Path to current filearea
    /D      Debug mode
    /G      Global mode at start
    /K      New definition of keys
    /S      Startup key

Refer the section  "Switches" for a  detailed description of  all switches and
their parameters.

If you are  working with a  R/O medium like  a CDROM drive,  you may be change
your  filearea  configuration,  depending  on  the  usage  of  the  EFT styled
FILES.nnn. If you prefer the standard handling, supported by RA/SBBS you  must
change  nothing.  RAFF  will  self  detect  the  associated  FILES.nnn  in the
listpath, defined in  "CONFIG.RA" (SBBS: Entry  in "FLSEARCH.BBS"). Since  the
EFT styled  FILES.nnn contains  additional informations  such as  path to  the
filearea, date  and size  of the  file, there  is no  need to access the CDROM
drive. In  this case  you -must-  change the  path entry  in "FILES.RA" (SBBS:
"FLSEARCH.BBS")  to  "~nnn",  where  the  new introduced leading character "~"
indicates  that  this  is  not  a  normal  path  and  nnn is the number of the
filearea.  There  is  no  other  way  to  tell  RAFF  the  path of the current
filearea.  Example:   "~150"  means  that   the  listfile  for  area  150   is
"FILES.150"  and  resides  in  the  common  listpath.  Warning: You should not
define a  real path  with a  leading "~",  if you  have already  one rename it
before using this option.  In case of a  wrong defintion, RAFF cannot  display
files  if  the  user  is  in  local  mode  on  a  CDROM  filearea.  For a full
description of FILES.nnn refer your EFT documentation.

RAFF displays a standard  menu unless you create  your own menu display  file.
If  you  prefer  to  use  your  own  menu,  you  have  to edit two files named
"RAFF.ANS" and "RAFF.ASC" and place them into your common textpath. This  file
will  be  display  as  the  menu  to  your  users.  If RAFF cannot locate this
supportfile,  a  builtin  standard  menu  will  be  displayed.  There are some
controlcodes  to  use  inside  the  support  files, refer the section "Control
Codes" for a summary of all controlcodes used so far.

All supportfiles should not exceed the size of 32k after the controlcodes  are
substituted.

The  attributes  of  colours  are  taken  from  "CONFIG.RA",  if  you  use the
hardcoded menu. Run  "RACONFIG" to change  the colours: "Text"  is assigned to
the  lowlight  colour  and   "Highlight"  to  the  highlight  colour  in RAFF.
Background  colours  are  always  set  to  black, regardless of the setting in
"CONFIG.RA".

All menus are  self explained, but  you can give  your users additional  help.
Create two files named "RAFF_HLP.ANS" and "RAFF_HLP.ASC" for this purpose.  If
RAFF cannot locate this supportfile, the menu item "Help" is not available.

Example are included inside the archive.



┌────────────────────────────────────────────────────────────────────────────┐
│                                Operations                                  │
└────────────────────────────────────────────────────────────────────────────┘

The  following  description  assumes  that  you  are  using the standard keys.
After calling RAFF you will see a menu with eight items:

    <A>  Area Access:  With this option it  is possible to toggle  between
         the global and  the local mode.  Local means that  all operations
         are  only  performed  on  the  current  filearea, the global mode
         spans all user accessible  fileareas. RAFF always start  in local
         mode, unless  you have  set the  "/G"-switch on  the commandline.
         The  current  state  will  be  displayed in highlight colour, the
         alternate option is displayed in brackets. You can simply  switch
         between these options by pressing the "A"-key.

    <C>  Change Filearea:  This  option works similar to the menu  type 50
         (Select  Area,  SBBS:  69).  It  allows  the  user  to change the
         filearea without leaving RAFF.  The selection menu respect  users
         restrictions so  he can  never select  an area  he has'nt  access
         too. Note that the choosen area will not remain if he returns  to
         the BBS, it is only valid during the current session of RAFF.

    <F>  Filename: Searching for  a filename specification. You can  enter
         any valid  filename or  a part  of it.  Wildcards (*  and ?)  are
         allowed.

    <K>  Keyword:  Searching   into  the  filedescriptions  for  a   given
         keyword.  The  search  is  case  insensitive.  You  can enter the
         keyword(s) in upper-, lower- or mixed case.

    <D>  Date: All files with a creation date on or before the given  date
         will be displayed.  The format of  date will be  checked, so your
         user  will  be  prompted  until  she/he  entered  a  valid   date
         specification.

    <N>  New  files check: Same  as above, but  the examined date  will be
         the last date the user was on.

    <->  Back to the BBS, terminates the current session of RAFF

    <?>  Displays the helpfile "RAFF.A??" if available. If not, this  item
         is not displayed.

With the  "/K"-switch on  the commandline  you can  change the key assignment.
The "/S"-switch simulate the first  keystroke, i. e. "/SN" on  the commandline
will start RAFF and show the newfiles as the first action.



┌────────────────────────────────────────────────────────────────────────────┐
│                            Available Switches                              │
└────────────────────────────────────────────────────────────────────────────┘

This is the summary of all commandline switches currently supported:

Switch  Usage                                   Example
------- --------------------------------------- ------------------------
/A      Pass the current area through RAFF      /A *0 for RemoteAccess
                        /A *U for SuperBBS

/C      Name of the configuration file          /C RAFF.CFG
    !Reserved for future use, currently
    not supported!

/D      Debugging: Display runtime error        -none-
    and the address where it occurs
    Danger: Waits for a keystroke!
    (will be removed after testing
     without notification)

/G      Start in global mode

/K      Replace the hard-coded keys             /K ACFKNDBH: New Key
                                 setting
    ACFKND-?
    ^^^^^^^^
    ││││││││
    │││││││└───── Help
    ││││││└────── Back
    │││││└─────── Date
    ││││└──────── NewFiles
    │││└───────── KeyWord
    ││└────────── Filename
    │└─────────── Change
    └──────────── AreaAccess

    You must set all eight keys even if
    you want to change only some of them.
    The standard keys are used if the number
    of given keys are wrong. Take care to
    define every key only once!

/T    Calculates the approximate transfer     -none-
    time for the connected speed. The
    calculation is based on a protocol
    effiency of 98%, this should be a good
    average value for a protocol like
    ZModem, MPt, BiModem or HS/Link. If an
    old fashioned protocol like XModem is
    used, the transfertime will be raised.
    On the other hand, for a error
    correcting link like MNP or LAP/M the
    transfertime will be decreased of
    around 17%. This should only help your
    users to calculate the transfertime in
    advance and cannot be correct at any
    time.


/S      Startup Key(s): Starts the application  /S N:  Immediate search
    first time with the given key(s)               for new files
    Two keys are possible. The pipe symbol
    ("|") will be translated to a <Return>
    and is only useful in combination with
    the "F"-operand.
                        /S F|: Immediate search
                               for all files

One or more of the switches listed above may be set on the commandline.



┌────────────────────────────────────────────────────────────────────────────┐
│                          Supported Control Codes                           │
└────────────────────────────────────────────────────────────────────────────┘

The following  control codes  are available  in all  support files  (currently
HelpScreen and TopMenu):

The ^K codes available:

ASCII   Char.   Function description
------- ------- -------------------------------------------------------------
11 52   ^K4     Name of the current filearea
11 79   ^KO     Number of minutes remaining this call
11 82   ^KR     Users baud rate
11 84   ^KT     Downloadlimit in KBytes

The ^R codes available (RAFF only):

ASCII   Char.   Function description
------- ------- -------------------------------------------------------------
18 65   ^RA     Key for Menu Item "Area Access"
18 66   ^RB     Key for Menu Item "Back"
18 66   ^RC     Key for Menu Item "Change"
18 68   ^RD     Key for Menu Item "Date"
18 70   ^RF     Key for Menu Item "Filename"
18 71   ^RG     Indicates global mode, replaced by literal "all" at runtime
18 72   ^RH     Key for Menu Item "Help"
18 75   ^RK     Key for Menu Item "Keyword"
18 76   ^RL     Indicates local mode, replaced by literal "this" at runtime
18 78   ^RN     Key for Menu Item "New Files"

The ^F codes available:

ASCII   Char.   Function description
------- ------- -------------------------------------------------------------
06 65   ^FA     Users full name
06 65   ^FB     Users city and state
06 70   ^FF     Users last calling date (MM-DD-YY)
06 79   ^FO     Users security level
06 80   ^FP     Users number of calls
06 81   ^FQ     Users uploads in files
06 82   ^FR     Users uploads in KBytes
06 83   ^FS     Users downloads in files
06 84   ^FT     Users downloads in KBytes
06 85   ^FU     Elapsed time this call in minutes
06 87   ^FW     Users firstname
06 55   ^F7     Users up/download ratio in KBytes
06 56   ^F8     Users up/download ratio in files



┌────────────────────────────────────────────────────────────────────────────┐
│                                Inside RAFF                                 │
└────────────────────────────────────────────────────────────────────────────┘

RAFF was  written in  QuickBASIC v4.5,  so I  should not  let you  look behind
RAFF, but  for better  understanding I  give you  some additional informations
how RAFF works.

All informations are  retrieved from existing  files, no files  are changed or
updated. After  calling, RAFF  reads "CONFIG.RA"  (SBBS: "CONFIG.BBS")  to get
the system informations  such as defined  colours, systempaths, listpaths  and
"EXITINFO.BBS" of the active node to get informations about the current  user,
his setting and  restrictions. After the  user made his  selection, "FILES.RA"
(SBBS: "FLSEARCH.BBS") will be read to determine the name and the path of  the
current/all  filearea.  If  the  area  matches  the  user  profile, processing
continues. If not, this area is skipped. Then RAFF is looking for  "FILES.BBS"
of the filearea. If  unsuccessful, RAFF assume a  CDROM and will be  searching
in  the  common  listpath  for  "FILES.nnn",  where  nnn  is the number of the
current  filearea.  If  there  was  no  "FILES.nnn"  found,  the  area will be
skipped.

Notes  on  searching  for  filenames  (non-CDROM-areas  only):  Prior  to read
"FILES.BBS"   RAFF   will   first   scan   the   directory   for   the   given
filespecification.  This  is  quite  faster  than  looking in "FILES.BBS".  If
there  are  matching  files  found,  processing  continues  with  "FILES.BBS".
Otherwise RAFF will be move over to the next possible area.

Notes on searching by  keywords: In this mode  it is not possible  to read the
directory first, so  this method will  be slightly slow  and should not  often
used on hudge fileareas. I try to speed it up in an upcoming release of RAFF.

Notes on  searching by  date/newfiles: The  first way  is to  examine the date
when "FILES.BBS" was last  updated. If the date  is before the date  specified
by  the  date/newfiles  option  there  could  not  be  new files in this area.
Remember that this only works if  "FILES.BBS" is not altered in any  way (i.e.
sorted)  during  your  daily  household  event  or  by  updating  the download
counters. Not  reliable, but  a way  to determine  new files  in fileareas. If
this check failed,  all entries in  the directory are  compared with the  date
specified by the date/newfiles option. All entries are collect in a table  for
later processing so that RAFF must not read the directory again. At least  one
entry should be in  the table at this  time: It is "FILES.BBS".  The table can
hold  a  maximum  of  1000  enries,  that  should be enough. On CDROM areas in
conjunction with a EFT styled "FILES.nnn" the directory of the CDROM will  not
be accessed since all informations can be retrieved from "FILES.nnn".

RAFF  was  developed  and  runs  successful  under  MS-DOS v5.00d, X00 v1.20ß,
SuperBBS v1.16 beta-4 and EFT v1.23ß.



┌────────────────────────────────────────────────────────────────────────────┐
│                             Acknowlegements                                │
└────────────────────────────────────────────────────────────────────────────┘

 RAFF is written in Microsoft's QuickBASIC v4.5.

 The directory access procedures are linked from the PBClone library.

 The FOSSIL is called using the QBX00 procedure, taken from the X00 package.

 Special thanks to Mike of "The Wizards  Inn II" who got the idea of  the file
 lister and made the first successful tests on a RA multiline environment.



┌────────────────────────────────────────────────────────────────────────────┐
│                              Error Messages                                │
└────────────────────────────────────────────────────────────────────────────┘

A disadvantage of  QuickBASIC is the  circumstance that in  case of a  runtime
error the system displays the errormessage, the adress -and- is waiting for  a
keystroke  on  the   local  site.  This   is  very  unuseful   for  unattended
applications  such  as  a  BBS  door.  For  this  reason  I replaced the error
messages  by  an  own  handling  procedure.  This  procedure only displays the
errorcode  and  terminates  the  program  (returns  to the BBS). The following
chart is a short but complete  summary of all possible error codes.  Note that
you should never  see some codes  like "Syntax error"  or "Out of  paper" from
this application...

If  you  are  able  to  repeat  the  error condition, call RAFF again with the
"/D"-switch on  the commandline.  This activates  QuickBASIC's internal  error
handling and give you more informations  about the error and the adress  where
it happend.


    Code    Description
    ------- -------------------------------------------------------
     2      Syntax Error
     3      RETURN without GOSUB
     4      Out of data
     5      Illegal function call
     6      Overflow
     7      Out of memory
     9      Sunscript out of range
    10      Duplicate definition
    11      Division by zero
    13      Type mismatch
    14      Out of string space
    15      String too long
    16      String formula too complex
    19      No RESUME
    20      RESUME without error
    24      Device timeout
    25      Device fault
    27      Out of paper
    50      FIELD overflow
    51      Internal Error
    52      Bad file number
    53      File not found
    54      Bad file mode
    55      File already open
    57      Device I/O-Error
    58      File already exist
    61      Disk full
    62      Input past end
    63      Bad record number
    64      Bad file name
    67      Too many files
    68      Device anavailable
    69      Communication buffer overflow
    70      Disk write protect
    71      Disk not ready
    72      Disk media error
    74      Rename across disk
    75      Path/File access error
    76      Path not found



┌────────────────────────────────────────────────────────────────────────────┐
│                         Trademarks and Copyrights                          │
└────────────────────────────────────────────────────────────────────────────┘

 Product:                       Copyright of:
 ------------------------------ ---------------------------------------------
 EFT - Enhanced Filetransfer    Michael Raus II
 MS-DOS                         Microsoft Corporation
 PBClone                        Thomas G. Hanlin III
 Remote Access                  Andrew Milner, Continental Software
 SuperBBS                       Aki Antman & Risto Virkkala
 X00                            Raymond L. Gwinn



┌────────────────────────────────────────────────────────────────────────────┐
│                             History Revision                               │
└────────────────────────────────────────────────────────────────────────────┘

Date            Ver.    Changes since last release
--------------- ------- -----------------------------------------------------
15.06.92    v1.06    ■ Areapath  did   not  match  (and   no  files    were
              displayed) after a user changed the filearea if  the
              areapath was defined  in lower-/mixed case  letters.
              Fixed it  today, areapath  will now  be translate to
              uppercase before comparing.

            ■ Changed the literal "XferTime" to "Time"

            ■ Allow  processing  of  security  level  >  32000 (RA
              only). Note  that the  level in  SBBS is  limited to
              32500.

            ■ Searching  now for  "FILES.RA" (SBBS:  FLSEARCH.BBS)
              first in  the current  directory. If  search failed,
              "FILES.RA"  is  assumed  to  be  in  the system path
              (defined with RA/SBBS environment variable).

            ■ Item  "C" (change  filearea): A  single <Return>  is
              now  accepted  as  a  valid  input.  In this case, a
              previous selected area will remain unchanged.

            ■ Detecting  now  the  installed   graphic  card   and
              switches to:  25 lines  for MDA/HGC/CGA  adapter, 43
              lines  for  EGA  adapter  and  50 lines for MCGA/VGA
              adapter. Since I could not test it with all  display
              types, I hope it will work. Note that the length  of
              the logical page is depending on users setting.

08.06.92    v1.05    ■ Displayed  occasionely  a  negative  value  for  the
              remaining timer after invoking RAFF (RA mode  only).
              Reason  was  an  error  in the calculation procedure
              due to a rounded field, fixed this error today.

            ■ UpK/DownK > 32M was not correct displayed in the
              statusline, fixed the problem.

            ■ Extended  the  operand  of  the  /S-switch  to   two
              characters.
              The pipe symbol  (|) has a  special function and  is
              only  valid  as  the  second  key:  It  simulates  a
              <Return>  and   works  only   with  menu   type  "F"
              (searching for filenames). This combination  enables
              an automatic display of all files at startup time.

05.06.92    v1.04    ■ Displayed wrong connection speed (always 0) in the
              statusline, corrected.

            ■ Changed controlcode ^KO: The remaining time will  be
              displayed as  an absolute  value, even  if the value
              is  negative  (occured  sometime  in  local   mode).
              Trailing and leading spaces are stripped away.

22.05.92    v1.03    ■ Included now an own ANSI emulation driver.

            ■ RAFF runs  now in a  window. Take care  off animated
              ANSI files. An attempt  to locate a position  on the
              screen  below  line  23  will  result into a runtime
              error. Line 24  will be reseved  now for the  status
              line (see below).

            ■ For nasty sysops, a statusline will now be shown at
              line 24 of the local screen.

10.05.92        v1.02   ■ Correct  a problem,  if long  file  descriptions
              could not be wrapped.

            ■ New  switch  /T:  Adds  the estimated transfer  time
              for  a  download,  depending  on  users   connection
              speed.  An   efficiency  of   98%  is   assumed   in
              calculation.  Note  that  the  previous usage of the
              /T-switch  (timer  function)  is  now covered by the
              /D-switch.


10.04.92        v1.01   ■ Fixed  bug  in  calculation behind  controlcode ^KO.
              The   remaining   time   should   now  be  displayed
              correctly (RA only).

            ■ If a user aborted the output just between two  lines
              of the  filedescription and  the first  file of  the
              next filearea  does not  exist, the  filedescription
              of the file was displayed. Fixed this bug today.

            ■ Included  15  new  ^F  controlcodes  and  2  new  ^K
              controlcodes.  Refer   section  "Supported   Control
              Codes" in this documentation for details of them.

31.03.92        v1.00   ■ First public release of RAFF



┌────────────────────────────────────────────────────────────────────────────┐
│                          Disclaimer and Warranty                           │
└────────────────────────────────────────────────────────────────────────────┘

THIS PROGRAM IS LICENSED  "AS IS", NO WARRANTY  IS GIVEN OR IMPLIED.  IN USING
THE PROGRAM YOU AGREE  THAT THE AUTHORS WILL  NOT BE HELD RESPONSIBLE  FOR ANY
DAMAGE OR LOSS OF  DATA CAUSED DIRECTLY OR  INDIRECTLY BY THE USE  (OR MISUSE)
OF RAFF.

I  make  no  warranty  of  any  kind,  express  or  implied, including without
limitation, any warranties of merchantability and/or fitness for a  particular
purpose. I  shall not  be liable  for any  damages, whether  direct, indirect,
special or consequential arising from a failure of this program to operate  in
the manner desired by the user. I  shall not be liable for any damage  to data
or property which may be caused directly or indirectly by use of the program.

RAFF IS FREEWARE: I  hereby declare the whole  material as public domain  (the
copyright is still  with me!), no  charge or fee  maybe given to  me or anyone
else for this application. Use it on  your own risk so long as you  want. Give
it away to everyone who need it.


               *** END OF DOCUMENT ***